8000 [ADD] template: doc repo template and guidelines to write doc · creodoo/documentation-user@bd235bf · GitHub
[go: up one dir, main page]
Skip to content

Commit bd235bf

Browse files
fgi-odoofgi-odoo
committed
[ADD] template: doc repo template and guidelines to write doc
1 parent 9400911 commit bd235bf

File tree

4 files changed

+116
-0
lines changed
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
:banner: banners/seo.jpg
2+
3+
=======
4+
Template
5+
=======
6+
7+
.. toctree::
8+
:titlesonly:
9+
10+
template/guidelines
11+
template/topic1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
===================================
2+
How to write user doc
3+
===================================
4+
5+
How to figure out a topic
6+
=========================
7+
* The documentation must be like a cookbook (one page = one problem).
8+
Topics must focus on business concepts, not Odoo concepts.
9+
10+
* Sometimes a single concept (payment term) may cover several business
11+
concepts, do 2 pages:
12+
13+
* Cash discounts on customer invoices
14+
* Defining and using payment terms
15+
16+
17+
How to write titles
18+
===================
19+
Talk "business need", not "how to use":
20+
21+
* Bad title: How to create checks?
22+
* Good title: How to pay supplier bills by checks?
23+
24+
25+
How to structure a page
26+
=======================
27+
A good structure for the document is:
28+
29+
* General Business concept
30+
31+
* what is it? why should you use it?
32+
* explain concepts needed to understand the flow
33+
* Business flows in Odoo
34+
* Configuration if needed
35+
36+
* simple flows
37+
* advanced flows
38+
* Specific use cases (questions)
39+
* Reporting
40+
41+
42+
How to write
43+
============
44+
45+
Who is the audience
46+
-------------------
47+
Target readers: lambda user, but not too stupid.
48+
49+
* Don't explain how to create/delete documents
50+
* Focus on business concepts
51+
52+
How to write good content
53+
-------------------------
54+
* The shorter the better
55+
* Not more than 80 char per row for easy technical reviews
56+
* Take clean screenshots (smaller possible, cut if needed,
57+
with red frames/circles to emphasize on important buttons, fields)
58+
59+
* Name screenshots this way in the section media repo:
60+
app_topic_#.png (e.g. ecommerce_catalog_01.png, ecommerce_catalog_02.png)
61+
* All documents & screenshots must be based on latest Odoo version.
62+
63+
.. image:: ./media/template_guidelines_01.png
64+
:align: center
65+
66+
.. tip:: Tips are always good for advanced features and to make the main paragraph
67+
lighter.
68+
69+
.. note:: When naming a button, write the text exactly like in the button,
70+
respecting the case. It's ok to have an uppercase here. When you use the
71+
name of a app, menu or field, put it *italic*. e.g.
72+
Once in *Sales Orders* menu, click the *More* Button.
73+
74+
* Give navigation paths for advanced handlings: e.g. go to
75+
a :menuselection:`Inventory --> My Account --> Overview`. Just give the menu
76+
to use and a screenshot. NO NEED TO GO INTO THE DETAILS: e.g. it opens a
77+
list view, click on *Create* button, click on *Save*. Don't do that.
78+
79+
* Include links to external documents: e.g. go to
80+
`Odoo Official Website <https://www.odoo.com>`_.
81+
82+
* Redirect to a demo database in order to illustrate a concept better (use action xml_id)
83+
84+
.. demo:action:: sale.action_orders
85+
86+
Create a Quotation
87+
88+
* Add links to related business topics at the bottom (can be in others apps)
89+
90+
.. seealso::
91+
92+
* :doc:`topic1`
93+
* :doc:`../sales/products_prices/prices/currencies`
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
===================================
2+
How to
3+
===================================
4+
5+
Subtitle
6+
=========================
7+
8+
Title 1
9+
----------------
10+
11+
Title 2
12+
----------------