New Vyatta documentation

[DaveRoberts]

For a while now, Vyatta users have been asking for more examples of how to configure various Vyatta functionality. In past releases (pre-VC4), we had something called the Configuration Guide that went along with the Command Reference to help provide examples of useful configurations. With VC4, we were unable to get things fully documented.

Over the past couple of months, we started to reevaluate our documentation strategy and decided that we really needed something new. With VC4.1.3 (Hollywood), we have implemented the first parts of that new strategy.

Now, we have carved up the product functionality into multiple guides that cover broad portions of the features. For instance, there is a High Availability Reference and a Security Reference. Each of these new books includes material that would have otherwise gone into the Command Reference and the Configuration Guide. Now, you can get both reference material about individual commands as well as configuration examples and extended discussion about features in a single book.

Currently, we have the High Availability Reference and the Security Reference available. Over the next few months, we'll be releases other similar manuals covering different parts of the product. Until we're done, we still have the Command Reference, but that will likely go away once we're done with each of the new manuals.

You can find the new documentation on the vyatta.org documentation page:
http://www.vyatta.org/documentation

Let us know what you think. Feedback is always welcome and we'll use it to make new revisions of these and other guides even better.

[ke4qqq]

Hi Dave,

Quick thoughts that are purely from the hip -
Why is this not something open to contribution from the community?
Aside from submitting bugs to Bugzilla in the documentation there is
no community writing or review process. A number of other OSS projects
accept documentation process, a place where the documentation
"professionals" lead the process and the community contributes, even
if it is only to do technical reviews.

There are some tremendously intelligent and knowledgeable individuals
within the community.


On Tue, Aug 26, 2008 at 6:03 PM, DaveRoberts <forum-users@vyatta.com> wrote:

[tmccafferty]

This is an interesting idea.

I don't think we would be looking for community contribs to the set of Docs that Dave posted yesterday, but there are other places where this would make sense.

Can you send some examples of what other projects are doing? or more specifics on what you had in mind?

-Tom

Tom McCafferty
Director of Marketing
Vyatta Inc.

[ke4qqq]

Sure - well think about the set of docs that openmaniak has on that
site. Those were very useful (don't know if they were kept up to date)
and honestly were better than the configuration data.

Another thing I have seen the Fedora Project do (although end user and
RH employees both collaborate on documents in all phases) is that they
will hand off a section and ask them to fact check. Do the
instructions work - is the reference manual for set interfaces
ethernet correct, etc. This is particularly true with version changes
- things like syntax change etc are often overlooked since most
documentation isn't rewritten from scratch. The work is relatively
small jobs, ie, breaking up a single chapter or a single reference
"page".

The other thing I have seen is "encouraging" wiki posts. Yes Vyatta
has a community wiki - or had, it appears to have disappeared. Yes
there was a wiki in the past - and yes no one used it, but look at
most OSS projects of any size and they couldn't live without a wiki.
Another project I contributed to in the past erected a wiki. And
essentially the community decided we were going to populate it. The
users started by looking through mailing list archives, harvesting the
good answers and putting a ton of content up initially. It became a
bit of a contest to see who would get the most content up. So why not
do that - have a contest, you push the most documents up in a given
month we'll tout your name and give you a Vyatta shirt or mug or
$swag. What tends to happen is that as new people come into the
project they are going to repeatedly ask the same questions.

I'll be honest that I am impressed with the idea of separate wikis for
paying customers (and I am one, or at least I work for one). I'd even
argue that harvesting support tickets for wiki content would be good
- make the wiki your tech support KB as well. It'll reduce your call
volume for support and benefit the community.






On Wed, Aug 27, 2008 at 3:23 PM, tmccafferty <forum-users@vyatta.com> wrote:

[tmccafferty]

We moved from the wiki to this new Drupal based site to allow for better design, integration and collaboration internally. On many pages we encourage users to contribute through comment fields or using direct entry forms but the truth is we could easily create a new class of users and allow them to edit pages. Let me think through where that would make sense and how we would go about adding it and I'll announce here when ready.

If anybody else has ideas for docs and contributing to Vyatta.org let us know

[adabbas]

1st allow me to thank you for this great product and all the efforts you are putting to develop it. I hope that one day I will be able to convince my management to replace all our Cisco routers with Vyatta appliances.

The idea of having different product functionally guides is sure welcomed. But why take away the "complete" command reference guide after finishing the small parts?? I believe that there should always be one document that contains all the commands of the system, a document that one will go through when he/she is not exactly sure what to look for

[DaveRoberts]

[adabbas]

Maybe when I feel more competent in using Vyatta, I will be able to help in maintaining the documents. I have good theoretical background and 5 years of IT experience (not counting the passionate youth years). My English is good for a nonnative speaker, and I am relatively a fast writer; I wrote my MBA thesis in less than a week