Add the beginning of a top-level architecture document
ClosedPublic
Actions

Authored by douardda on Nov 16 2018, 5:09 PM.

Details

Reviewers

vlorentz
olasd

Group Reviewers

Reviewers

Commits

rDDOCe8d48567534b: Add the beginning of a top-level architecture document
rDDOCc0f71e6c7504: Add a swh_substitution file and make it included in every rst file
rDDOC5e339b44255d: Add a glossary and begin to use it in the getting-started page

Summary

also add a glossary and begin to use it in the getting-started page

Diff Detail

Repository

rDDOC Development documentation

Lint

Automatic diff as part of commit; lint not applicable.

Unit

Automatic diff as part of commit; unit tests not applicable.

Event Timeline

douardda created this revision.Nov 16 2018, 5:09 PM

Herald added a reviewer: Reviewers. · View Herald TranscriptNov 16 2018, 5:09 PM

Harbormaster completed remote builds in B2432: Diff 2106.Nov 16 2018, 5:09 PM

What do the pipe in |swh| mean?

Regarding docs/images/general-architecture.svg: I really like it. Could you add the names of involved technologies (eg. in a box with logo->name matching) so they are easier to search later on?

Regarding mermaid graphs: The text is too small to read without zooming in. Increasing the font size should fix that without breaking the layout.

docs/architecture.rst
8 ↗	(On Diff #2106)	Missing a closing parenthesis.
40 ↗	(On Diff #2106)	and inserts nodes and edges in the graph.
65 ↗	(On Diff #2106)	"seauence"
73 ↗	(On Diff #2106)	"gitlba"
docs/glossary.rst
33	maybe explain the difference between a SHA1 and “git-like” SHA1 in that glossary as well?

vlorentz requested changes to this revision.Nov 16 2018, 5:39 PM

vlorentz added inline comments.

docs/glossary.rst
137	Don't forget this :)

This revision now requires changes to proceed.Nov 16 2018, 5:39 PM

vlorentz added inline comments.Nov 16 2018, 5:46 PM

docs/architecture.rst
11 ↗	(On Diff #2106)	Postgresql
31 ↗	(On Diff #2106)	choreography
43 ↗	(On Diff #2106)	information (it's uncountable)
docs/glossary.rst
122	prioritization

In D668#13808, @vlorentz wrote:

What do the pipe in |swh| mean?

http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#substitution-references

Looks like the substitutions file is missing?

Cool stuff ;)
Thanks.

Fix reported typos and remarks

Harbormaster completed remote builds in B2447: Diff 2125.Nov 19 2018, 12:14 PM

It's perfect now :)

Thanks!

This revision is now accepted and ready to land.Nov 19 2018, 1:41 PM

Several modifications

Summary:

replace mermaid with plantuml
use sphinxcontrib.images
better glossary

Harbormaster completed remote builds in B2526: Diff 2186.Nov 22 2018, 1:55 PM

douardda added a child revision: D696: make-doc: refactor doc build system to build the doc as a whole.Nov 22 2018, 2:42 PM

In D668#14496, @douardda wrote:

Several modifications

Summary:

replace mermaid with plantuml

use sphinxcontrib.images

better glossary

The diff to the previous iteration looks fine to me!

Regarding the glossary, we also had https://wiki.softwareheritage.org/wiki/Glossary ; once this is pushed the wiki glossary should be deprecated/deleted in favor of the docs.s.o one. In the meanwhile there might be entries there that are missing here (I haven't checked, but wanted to mention potentially useful previous work :-))

In D668#14654, @zack wrote:

Regarding the glossary, we also had https://wiki.softwareheritage.org/wiki/Glossary ; once this is pushed the wiki glossary should be deprecated/deleted in favor of the docs.s.o one. In the meanwhile there might be entries there that are missing here (I haven't checked, but wanted to mention potentially useful previous work :-))

I've seen this. Ok to deprecate it ASA this diff is published and the doc is online.

In fact, there are other place(s) where we can find kind of partial glossaries, especially https://docs.softwareheritage.org/devel/swh-model/data-model.html#software-artifacts . Not sure how to deal with this later one however. It makes sense to keep these definitions explicitly in this document, IMHO.

In D668#14656, @douardda wrote:

In fact, there are other place(s) where we can find kind of partial glossaries, especially https://docs.softwareheritage.org/devel/swh-model/data-model.html#software-artifacts . Not sure how to deal with this later one however. It makes sense to keep these definitions explicitly in this document, IMHO.

Agreed.

I think we can walk the fine line between a glossary (short definition, for mnemonic use) v. definition (long definition, with all the details). The Data Model can very well be the source for the latter; the glossary for the former. And for each of the relevant entries the glossary can link to the Data Model under a "for more information see [...]" notice.

Closed by commit rDDOC5e339b44255d: Add a glossary and begin to use it in the getting-started page (authored by douardda). · Explain WhyNov 23 2018, 2:50 PM

This revision was automatically updated to reflect the committed changes.