Ticket #2286 (new task)

Opened 9 years ago

Last modified 8 years ago

The static doc should be organized into audience categories

Reported by: madarche Owned by: madarche
Priority: P2 Milestone: CPS 3.5.7
Component: Community Version: 3.5.1
Severity: normal Keywords:
Cc:

Description

The static doc located at  http://doc.cps-cms.org/ should be organized into audience categories.

At the moment this doc lists all the static doc sorted by products.

There should be a higher level sorting done on the audience for those docs:

  • system administrators and technical web masters
  • developers
  • maybe website designers (especially regarding CPSDesignerThemes)

Change History

comment:1 Changed 9 years ago by madarche

This audience sorting can be done in 2 ways in docbuilder:

  • the centralized approach: writing doc_directories.xml accordingly
  • the flexible-dynamic-decentralized mediawiki approach: specifying in each static .txt doc to which categories it pertains and have the doc builder generate a doc sorted by categories, using all the live categories found

comment:2 Changed 9 years ago by gracinet

Hmh tough choice, the pros and cons are rather orthogonal. The first has the obvious drawback that any new directory must be referenced, and all the existing documentation has to be segmented in subdirectories right away (a good thing in itself)

The second means that creating a new category can be done only by editing hundreds of files But that can maybe be alleviated by using a conventional file giving a directory a list of default categories, meaning that all files that don't have an explicit list of categories get the ones from the directory (a replacement, not a merge). Another drawback (actually the same from a different perspective) is that it makes creating new aggregated docs harder (say for a specific or even private purpose), whereas copying and editing an XML file is always easy.

Therefore, my opinion would be to keep the down-to-earth approach at least available. If I understand correctly, it's just a matter of passing the XML file as argument to the script, so it'd simpler for now.

About the tag oriented strategy, would you think using the standard (but meant for HTML only)  meta directive of RST for that purpose ? I'm thinking of keywords and/or coverage.

comment:3 Changed 8 years ago by madarche

For this task  http://sphinx.pocoo.org/ should be considered.

Note: See TracTickets for help on using tickets.