Skip to content

Instantly share code, notes, and snippets.

@kelunik
Created August 14, 2016 14:30
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save kelunik/bf80c2df6e34d6e9c4d690f9f098c7ca to your computer and use it in GitHub Desktop.
Save kelunik/bf80c2df6e34d6e9c4d690f9f098c7ca to your computer and use it in GitHub Desktop.
Documentation Management System

I plan to write a new documentation system, because I couldn't find any system that suites my / our needs at amphp. It has to support multiple packages and their various versions (at least major.minor, bugfix versions will just update the current version). Furthermore, there needs to be support for tutorial series. It's planned to build these from markdown files in ./doc currently.

But we can write as much documentation as we like, the key point is that it must be usable for those that really need the documentation to learn how things work. So I'm asking you here. As a new user of a framework / library / package, what's your preference?

  • What do you need in a documentation system?
  • What is your preferred way for navigation?
  • What should tutorial series look like?

And two more questions if you want to publish your own documentation:

  • How do you want to write documentation?
  • How do you want to handle versions?
@bwoebi
Copy link

bwoebi commented Aug 14, 2016

For the latter two questions:

  • with simple but powerful markup (i.e. nothing as overkill as docbook)
  • maintain a version history on each page. The main content shall always be up-to-date with the newest version, for older versions, look into the version section. The tutorial should not be affected by versions and always be up-to-date with the newest version.

@kelunik
Copy link
Author

kelunik commented Aug 14, 2016

@bwoebi If you don't version the tutorials, they won't be available once a new version is released. On the other hand, if you use the contents of /doc you won't be able to update older docs without a release.

@bwoebi
Copy link

bwoebi commented Aug 14, 2016

@kelunik not sure what you mean? The point is that the old versions of tutorials are not available anymore after a new version is released. You shall learn with the newest version; when an older version does not support it that way, then please go to the docs which contain specific info.

@kelunik
Copy link
Author

kelunik commented Aug 14, 2016

Why not just have the tutorials versioned as well?

@bwoebi
Copy link

bwoebi commented Aug 14, 2016

I see no point in it? I have no problem with an archive of them for older versions, but I do not think it should be inline.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment