Re: Summary of modular user-story-based docs terminology

"Brian (bex) Exelbierd" <bex@xxxxxxxxx> · Fri, 20 Jan 2017 23:28:22 +0100

-- 
Brian (bex) Exelbierd | bex@xxxxxxxxx
+420-606-055-877 | @bexelbie http://www.winglemeyer.org

On Jan 20, 2017, at 7:14 PM, Pete Travis <me@xxxxxxxxxxxxxx> wrote:

On Jan 20, 2017 10:38, "Petr Bokoc" <pbokoc@xxxxxxxxxx> wrote:

        Hello everyone, 

          We've been working on modular documentation internally (in Red
          Hat) for a while, and since our efforts and the
          modularization/modernization initiative Fedora Docs align to a
          large degree, we want to share with you what we have so far.

          The following is a short digest of our progress so far. We
          still need to decide how to put everything together and how to
          keep track of various articles, this is mostly thoughts on
          various types of content. Hopefully you'll find this useful;
          I'll follow this up later with some additional ideas.

          Modular
              Documentation - Definitions used for RHEL docs
          NOTE:
              This document is not intended as a complete reference
              guide for documentation-related terminology.

          Module
              = a building block of information with a well-organized
              structure that can be combined with other modules into a
              larger assembly;
              reused piece of content

              Procedural
                  module = describes steps to accomplish a task

              Conceptual
                  module = explains a concept; i.e. not based on task

              Reference
                  module = lists links to related reference information,
                  such as man pages or other documentation, including
                  other modules or assemblies

          Assembly
              = A collection of modules -- a docs realization of a user
              story

          User
              story
              = a short description of something the user wants or needs
              to do to achieve a goal. 

              Example:
                As
                  an administrator, I want to set up authentication to a
                  critical system in my infrastructure (gateway VPN,
                  accounting system) to only allow users authenticated
                  via strong authentication methods (two-factor
                  authentication).

              As
                  opposed to a use
                  case
                  = a description of interactions between the system and
                  the user or other systems.

          *snip*

I really like this model, especially the module classes.  Server side includes came up at some point in an assembly-related discussion I had with Bex at some point; that's always seemed like a crafty way to catch a security lecture from a sysadmin :P

That said, server side includes could allow us to more easily assemble articles using components from multiple source repositories, afaik something that no publishing tool can do easily.  Kevin, would you please weigh in on the idea?

I think I have a model for building these that won't require server includes for this. I may want them for an unrelated piece though. 

I hope to have a demo ready by 30 Jan. I've got several different pieces ready. 

Regards,

bex

_______________________________________________
docs mailing list -- docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe send an email to docs-leave@xxxxxxxxxxxxxxxxxxxxxxx

Re: Summary of modular user-story-based docs terminology

Modular Documentation - Definitions used for RHEL docs