Structured documentation

[nidico]

There's quite some Adhocracy documentation, but it's spread over different places and partly mixed up with liquid democracy concept descriptions. This needs to be cleaned up.

There currently is:

• Developer / API documentation in the main adhocracy source code. On commit, this should be deployed to http://adhocracy.readthedocs.org/.
• Installation instructions in adhocracy.buildout README.md.
• End user documentation in static html files in the source code and in the adhocracystaticpages wordpress.
• All kinds of old stuff in http://trac.adhocracy.cc/
• Probably more.

There should be:

1. One main place for documentation, which constantly evolves. This should include:

   • Adhocracy concepts (useful for everyone)
   • End user documentation (how do I...) - this shouldn't be important if the above (Adhocracy concepts) is done right
   • Developer documentation (to understand the code, used modules, etc.)
   • Administator documentation (installation, upgrading, deployment setups, also troubleshooting - s. #74)
   • Contributor guidelines (s. #75)

   We have previously discussed that this is best done with reStructuredText in the source code docs folder, which is automatically pushed to http://adhocracy.readthedocs.org/ on commit. The alternative would be the GitHub wiki (which is now disabled).

2. One place for the current state of meta-discussion on how to move forward. I'd propose this should be the GitHub issue descriptions, which can be discussed in the issue comments and on the mailing list.

[phihag]

Don't forget the installation/quickstart instructions, for users as well as developers (I hesitate to just edit it in). Either github or the mailing list is fine. To me, issues seem easier to manage on github.

[MicaSz]

For the "Adhocracy concepts" part I would recommend to write a "lean and mean" documentation comparable to a standard "system requirements specification (SRS)", e.g with:

• a high level feature list
• the central use cases supported
• a conceptual data model (just the conceptual "business objects" and their relationships), perhaps additional with their "business rules"
• state charts, if needed & helpful
• the access & authorization concept (roles & their rights) Other parts of a SRS like user interface specifications, system operations, nonfunctional requirements etc. shouldn't be needed or are better part of the user documentation.

Your Opinions? I just started with the data model to get a better understanding of adhocracy features, but didn't get finished with it cause lack of time. Who is interested or wants to help with this?

[nidico]

@phihag - I had subsumed installation / quickstart under deployment under administrator documentation, but I've made it more explicit now. Okay like that, or do you want to see it somewhere else?

[nidico]

@MicaSz - I think that the bullet points you mentioned are useful in a documentation, and helping hands on this are very welcome! However, I would rather consider it as a system description than a requirement specification (as the system already exists right now, has grown and is simply not based straight well-formulated requirements), but that's only words.

My main focus is the conceptual data model, as this is a central point to grasp for both users and developers. I'd also like to connect this to the Liquid Democracy / Direct Parliamentarism concepts, as this explains some design decisions. Should we work on this together in a separate issue?

For the rest:

• A high-level feature list would be useful in the documentation introduction
• State charts - why not, if it's useful to explain something, but I wouldn't do it systematically
• Access & Auth - yes, this would also be useful in the general concepts section. I would keep that rather high level as well, as the underlying techniques will be upgraded soon.

Doing proper requirement analysis with use cases and such would also be useful, but more in terms of further development, not documentation of the current system.

[MicaSz]

@nidico - I agree. At our company we call such conceptual system documentation a "System Specification" (in german "fachliche Systemdokumentation"; we use the term "System Description" for the technical documentation, like e.g. architecture, design etc.). Both are in fact lifecycle documents, whereas SRS' are used mainly for release "scoping" before implementation. But thats only words, I agree ;-)

Ok, I summarize the parts for such a conceptual documentation:

• a high level feature list
  What do you think about the "User Story" concept, used in SCRUM projects? I think it may be useful for the documentation of "usage features".
• a conceptual data model
  Thats one of my favorite models. I'd like to help you with that, also I'm really rather a newbie with adocracy. But perhaps that's an advantage ;-)
• access & auth concept (-->high level)
• system behavior (State Charts) - only on distinct topics

I would also recommend:

• an application process view: Which real world activity sequences are how supported? (--> "Business Process Model"). Of course only a rough very high level point of view, to show the averall usage sequence / possibilities.