A suggestion for better manuals.
Here, I am copying the question's description since the question expired.
I was looking at the Brewtarget user manual and this got me thinking about the fact that there must be a better way of managing contributions, language and formats.
Since the best community written book I know is pro-git, I went and looked at the technology they are using. First, they use the AsciiDoc encoding format that is very similar to Markdown. It is definitely clear enough that anyone could contribute after a quick glance at an example. Since it is similar to the Markdown format, I suspect some of you have seen similar examples when editing a Wikipedia article.
They are using the Atlas continuous integration manager for written publication but this is only an easy to use automation process. It could be easily emulated by someone on each release or, I imagine, a bash script.
The can then be compiled in an compiled html like we have right now, or a PDF, or most ebook format.
The other important point they have is that the book is in its own git repository and therefore contribution can be managed independently of the rest of the application. Which make sense since it is a different artifact. Since there is no clear solution to handle internationaliz
So there it is, I would like you opinion and comments on this. If you think this might be interesting, I could setup the basic infrastructure needed to replicate what we have right now and let everyone play with it.
Blueprint information
- Status:
- Not started
- Approver:
- None
- Priority:
- Undefined
- Drafter:
- Maxime Lavigne
- Direction:
- Needs approval
- Assignee:
- Maxime Lavigne
- Definition:
- Approved
- Series goal:
- None
- Implementation:
- Unknown
- Milestone target:
- None
- Started by
- Completed by
Related branches
Related bugs
Sprints
Whiteboard
Work Items
Work items:
Setting up repository: DONE
Rewriting manual to Asciidoc: DONE
Reviewing with other developers: INPROGRESS
Documenting in a wiki page: TODO