Community mailing list archives

Re: Guidelines for User Documentation

Martin Trigaux (mat)
- 07/31/2015 08:06:46
Just a comment to reassure the ones afraid by the "developer oriented" aspect of GitHub if you need to report issues.

No technical knowledge is required to create an issue. You will just need a free account and explain in plain English the error or improvements you would like to submit and somebody will discuss or integrate the changes.


On 30/07/15 17:10, Martin Trigaux wrote:
<blockquote cite="" type="cite"> Hello all,

Just a quick update on the documentation. Thanks to everyone joining the effort.

When writing the documentation, please keep in mind a few things:
Only assign yourself to a couple of chapters at a time. That's great if you wish to write many chapters but don't block chapters where other could also write something.
Don't forget to update the status of the task. Once the line is in "reviewed" state, we will process it to merge it to official documentation.
Be also sure to leave your document with the permissions "Anyone with the link - Can comment"
When taking screenshot, try to keep a minimal image. Only capture the relevant part of the screen and avoid full page screenshots.

We have already published a few pages:
Assets management
Payment terms
Invoicing process
Refund an invoice
Create a bank account (will be build tonight)
Take a look at these pages to understand how to construct your document. If you notice an error/improvement in the already published page, please create an issue on GitHub (or a pull request if you know rst) with your suggestions.

Finally, as you may have noticed, we have merged the new design into Odoo enterprise branch so there is no need to work on several runbot in parallel to test the new design as I stated in my first message.
You can now test your features on the runbot master enterprise.
On every build you get two databases, one with every module installed (the one you are getting if you click on above link) and another one with only base modules (you need to disconnect first) if you want to test with only a few modules installed. As before, you have the administrator (admin/admin) and a demonstration user(demo/demo) that you can use as you wish.

Thank you all.
As always, we are available if you have questions.


On 20/07/15 13:17, Martin Trigaux wrote:
<blockquote cite="" type="cite"> Hello all,

Thank you to all who have starting writing or reviewing the new user documentation for future version 9 (initial announcement). Everything seems to start well.
Here is a few reminders for those who would like to jump in:

Check the spreadsheet at . We have increased the table of content with more subjects. Don't hesitate to take free slots as writers or reviewers if you are confident in one subject.
If you are creating a new Google Docs sheet, don't forget to allow users to put comments for the review.

If you are afraid of the blank page or don't know where to start, do not hesitate to reuse content. The v7 documentation is probably a good start. Sometimes a bit outdated or not perfect but still a lot of valid information. You can also take example on the assets management page (published version).

If you need to test some features or needs to take new screenshots (to do with the new design), please use one of the following link:
Runbot master with new design (from development enterprise branch)
Runbot master enterprise (in which the new design will be merged soon, latest features)
Runbot master community (same as above, minus enterprise modules)
Keep in mind that these branches are still in heavy development, features may be broken from time to time so if something stops working, check a bit later to see if it has been fixed (you can ping me if the feature you are documenting stops working and isn't fixed after a few days).

Once both the writing and reviewed are done, we (probably xml or myself) will convert the pages to RST to push to GitHub (don't hesitate to ping me, if we miss one reviewed page). Once this is done, the whole edition work will be switched to GitHub, so this will be the place for further updates.
If you notice an error, typo or need for rewriting some parts of already published pages, please report an issue or, even better if you can, submit a correction to the existing files (we will add buttons to make that easier from published documentation).
The documentation is build nightly so don't worry if your changes are not automatically published.

Last but not least, if you are not sure where or how to start, please join our online kick-off meeting this Monday July 20 at 16.30 CET (Brussels time) (or in other timezones)
On G+:
On Youtube:

Martin Trigaux
Odoo (Formerly OpenERP)

Martin Trigaux
Odoo (Formerly OpenERP)

Martin Trigaux
Odoo (Formerly OpenERP)