[Freeipa-devel] FreeIPA documentation: getting started & devel docs (FOSDEM takeaways - Software Archaeology for Beginners)

[Nathan Kinder]

On 02/25/2014 01:32 AM, Petr Spacek wrote:
> Hello list,
> 
> I have seen talk "Software Archaeology for Beginners" from FOSDEM 2014
> [1] and I have couple notes:
> 
> 1) User docs:
> Make sure that project's documentation tells its own story:
> Documentation is not so useful if it is a bunch of unrelated documents.
> Make sure that there is 'introduction' document starting with project
> description. The 'story' should continue to installation and very basic
> configuration and use cases.
> 
> There should not be a 'gap' between steps like missing steps between
> installation and client configuration etc.
> 
> We have something like that in RHEL IdM guide. Should we add "Getting
> Started" link to the very beginning of
> http://www.freeipa.org/page/Documentation#User_Documentation ?
> 
> Maybe the RHEL guide is too huge and scary for 'getting started' so we
> would need to write something/compile it from existing blogs posts etc.
> 
> 
> 2) Pictures with a story are nice:
> Diagrams with system components are more useful when they *visualize
> some basic workflows step by step*.

I find diagrams very useful for workflows as well.  They are very useful
when used in combination with your typical architecture diagram.  I used
http://www.websequencediagrams.com to generate workflow diagrams for the
Password Vault design proposal:

    http://www.freeipa.org/page/V3/Password_Vault

I'd recommend trying that tool, as it's really pretty quick/easy to
write the "code" to cretre the diagram, and you don't need to mess
around with an actual drawing program.

-NGK

> 
> Imagine one SSSD client and one IPA server and describe what happens if
> the user enters his username and password to login prompt.
> 
> - Arrow #0 from NSS db /passwd/ to SSSD component /s1/ with description /d/
> - Arrow #1 from SSSD component /s1/ to IPA component /i1/ with
> description /d/
> - Arrow #2 from NSS db /shadow/ to SSSD component /s2/ with description /d/
> - Arrow #3 from SSSD component /s2/ to IPA component /i2/ with
> description /d/
> etc.
> 
> Such diagram not only helps to new developers but also gives tremendous
> help to people debugging the whole solution. (We have to admit that
> debugging is always PITA.)
> 
> 
> As usual, this sounds like a good task for newcomers (sorry Adam! :-).
> 
> [1]
> http://video.fosdem.org/2014/Janson/Saturday/Software_Archaeology_for_Beginners.webm
> 
>