Wiki Formatting? (Taken from Cacti repo)

netniV commented 6 years ago

This issue is a continuation of Cacti Issue #924 with a copy of that issues details below

@jpartain89 posted on 23 Aug 2017:

What language are the wiki pages supposed to be coded in....

Because there's a ton of // items and ; at the beginning of lines....

These don't exactly make sense, especially if you're trying to use MarkDown, as other parts of the docs ARE appropriately using...

If there is a need to change the Wiki pages/Documentation to a specific language, I'd be more than happy to help, but in need of a singular language/format.

@cigamit commented on 23 Aug 2017:

Thanks. We are currently reviewing the whole Wiki/Documentation effort.

Can you post a few links of those pages?

@devsibwarra commented on 23 Aug 2017:

@cigamit https://github.com/Cacti/cacti/wiki/Linux-Installation is one example. Looks like a spliced mix of MediaWiki and MarkDown was used on that page

@cigamit commented on 28 Aug 2017:

Okay, noted. Right now we are working on a refresh to the documentation plan. We have created a documentation repository, and we will be breaking the rather large manual.md into categories that can be displayed in the various GUI sections of Cacti.

For example, we will have a documentation section on Presets, Presets > VDEF, Presets > Colors, Presets > GPrint Presets, Presets > Data Source Profiles, etc.

If you have suggestions for Chapters, we would welcome them. Pull requests there are also welcomed. My first thought would to be to align the markdown files similar to how our HTML documentation reads, but to add these various sections so that we can link to them inside the GUI.

@jpobeda commented on 28 Aug 2017:

Whatever you decide, please do it thinking on multi language so people can help with translations in the future.

@cigamit commented on 29 Aug 2017:

Tony would like help first updating the documentation in English, then we will create independent language directories such as 'en', etc. He please use the Wiki on the documentation repo to share thoughts on chapters. Then, if you can help with English first, we will then move to other languages.

Pull requests will be the way we take updates as with everything else.

@jpobeda commented on 30 Aug 2017:

I'm happy to help.

@ronytomen commented on 11 Sep 2017:

Good to know!

I'm going to move this issue to the documentation repository.

Ok, I can't move issues.. lol

It will stay here to remind me.

I've now recreated this as a new issue. And will be closing/locking the old one.

jpobeda commented 6 years ago

@netniV , @ronytomen

If I was to update some of the existing documentation to reflect the current changes on Cacti 1.x how would you like me to do it? For instance the whole install/upgrade section should be re-written since we now got an amazing wizard to get it done including requirements and setup steps.

I was also thinking that it might help to re-think a documentation content index to be used as a 'guide' so we can also know what's the scope and what needs to be done or updated or re done, etc.

I've been making notes of out-of-date data, pictures, typos, etc, etc.

Can you guys please advise? I'm keen to help on this topic which I'm a lot less harmful than coding :D

netniV commented 6 years ago

I've been trying to write something to convert the old documentation over to markup as I'm not entirely sure we have everything we previously had. However, that whole bit of work is on hold until the beta is officially out.

We do need to get it updated though as quite a few things have changed. The installer is definitely one of them. Most of those is now in place, though i'm still making a few more changes. The look and feel of several pages will have changed again over the past week within the installer.

If you want to submit any changes, we can review/merge them. I will be checking through the commits made once I finish the old to markup conversion, then seeing what's different and making sure we have it all in place and up to date.

netniV commented 6 years ago

If you want to verify that we have all the sections from the docs.cacti.net on this repo, then please feel free to do so 👍

jpobeda commented 6 years ago

I'll verify what you asked.

I wouldn't submit any changes without knowing the plan and its scope. So far it looks like you're waiting to get that markup conversion done before doing anything else.

What I was trying to say before is if you got a plan and the scope of it, we could start writing the missing, old, and/or new sections, for example current content menu does NOT include discovery and automation or any of the almost 20 plugins absorbed to the core. So will those be new sections with their own .md files?

I'm not too worry about pictures, they'll come last, that's really the easiest part to make and to update as well.

jpobeda commented 6 years ago

@netniV , may I ask what did you do pull this files from docs.cacti.net?

I'm not sure if I'm looking at something you decided to merge or consolidate or you ran some sort script to pull them leaving behind a lots of section and subsections.

In some cases it looks like the text was just cut off, if you look at "Principles of Operation" the first diagram is gone plus 2 lines of text.

Another example is 'User Management' which is missing AD Integration part.

I'm taking this as ref https://docs.cacti.net/manual:100

jpobeda commented 6 years ago

Crap, I now realise that I should be looking at this branch https://github.com/Cacti/documentation/tree/Converted right?

netniV commented 6 years ago

I have created the Converted branch where I was putting through the converted information, as I suspected that the main documentation was not complete.

You have confirmed now that the main branch is missing information which is what I suspected. So, if we have a quiet week on changes needed for the beta, I will endeavour to get the documentation branch pulled in from the old site to a place were it just needs to be reviewed to look nice.

netniV commented 6 years ago

Actually @jpobeda, if you can see the missing stuff, it may be easier to simply add it and maybe review the pages. I know that @ronytomen is also making some notes too so anything you do will help out like the images you've recently submitted.

I'm not really going to have that much time to sort out the conversion script and then double check everything afterwards too. If you can give that some momentum, that would be great.

jpobeda commented 6 years ago

@netniV I'll have a look against converted branch, I suspect that would be a better a idea to review that branch and flag sections that need to be updated, sections that need to be created, content that needs refresh, etc.

Master/Develop branch is way behind the converted branch.

netniV commented 6 years ago

There is no more converted branch.

netniV commented 6 years ago

I have been working on the Command-Lines-Scripts.md and Variables.md today as I needed to utilise information from them. Variables, for example was missing many tables so if you see the changes I made, this is the kind of thing we are looking for.

netniV commented 6 years ago

Things to note for anyone who may be updating any documentation are:

Any examples should be enclosed with three backticks and the language of the example. The following are basic language examples::
- console If it's a shell example
- php if it's website code
- sql if it's an SQL statement
- javascript if it's javascript
- Trailing spaces should be removed, I used the following command:
```
sed -i -e's/[[:space:]]*$//' Variables.md
```
Lines not within code blocks or tables should be wrapped at column 80.
- This one was fairly easy for me as I use nano, so I simply set my console width to be less than 80 characters, then using Ctrl-J on each paragraph to justify it.
- Note, I would not recommend using a command line tool like wrap etc. unless they are markdown aware and can ignore code / table blocks since these should maintain their length.
Use only the # header format and you should normally only go up or down one level at a time. At the moment, the only caveat to this has been using six #'s as the style for Table/Figure captions eg:
Table 1-3, Example Table containing an example
There should always be a blank line gap between any elements:
- code blocks
- headers
- list blocks
List elements should not have extra spaces between the hyphen and the text. When using multi-level list styles, indent by three characters.

There are other rules that the Markdown checker is throwing out but for now, try to stick to the above and we'll work on the rest.

netniV commented 6 years ago

So, I have created a standards document. It hasn't been fully reviewed yet, but it does confirm to the standards we've set out (at least I hope it does!!)

https://github.com/Cacti/documentation/blob/develop/Documentation-Standards.md

jpobeda commented 6 years ago

Looks good, as soon as I get something ready I'll push a PR to see I'm on the right track

netniV commented 6 years ago

If you have a linux box, install Ruby, and then run gem install mdl and you can run the syntax check script.

jpobeda commented 6 years ago

@netniV

I started to work on this, finally. Just to make sure we're on the same page, we first want to pull everything from https://docs.cacti.net/manual:100 and make sure we got them all (following md standards), and then go through the contents and update + add new sections, etc, right?

netniV commented 6 years ago

We need to make sure we aren't missing any vital information from the old manual. Things have changed from what was written so that will also need to be updated too. For example, the variables were a little out of date, so I updated them whilst I was copying the missed info.

As for sections, I don't think we need too many more. If you think some reordering needs doing, suggest away as nothing is set in stone right now. I would suggest picking a section at a time to update so it's not just one massive update.

It may be easier to do things in the following order:

Pick a section and create a branch in your repo
- Review titles for uniqueness
- Review content for missing info/tables/images
- Review links to other documentation pages
  - If a section hasn't been updated with info that is needed, make a note to update the URL later
  - Don't update the outdated section as that should have it's own repo
- Update info where possible
- Submit a pr, rinse and repeat

This will allow reviews of individual pull requests without affecting others, so if we hold one back, we can still submit others.

jpobeda commented 6 years ago

Yep, we're good then. It'd be nice to flag sections that have been reviewed (at least once).

I'm currently working on Installing-Under-Unix (which doesn't exist on current repo) as it happens, setting snmp up used to cover AIX, Solaris, HP-UX. Links are pretty much all dead and apart from that, does cacti still want to have them mentioned for 1.x? If so, blank them out and leave a TBD flag?

Once again, I see inconsistencies for example with General-Installing-Instructions.md It seems you have attempted to cover Unix/Linux installation instructions leaving some stuff behind. This title doesn't exist on cacti.net so I'm presuming you've created it. Add some light pls

If we're covering *nix and win installation, I don't see the point of having a "general" one to be honest, but is up to you. Just clarify if you still want the unix one or I'll move to the next section.

cigamit commented 6 years ago

Seems like we only need a planning.md that is not tied to the whole document, or @ronytomen needs to enable the Wiki for this repo, so that people can take topics.

ronytomen commented 6 years ago

Ok, I finally reconciled my thoughts on this and how we can proceed!

I have created a Project to track all the issues associated with getting the documentation updated for the 1.2 release.

As for tracking each section, if either of you want to create issues for each section that needs checking/updating, feel free to do so. Whatever works to help people divide up the work.

I'm also still contemplating how to support multiple languages here in documentation land, here is my first stab at a structure:

Table of Contents Files:

README.md
README-bulgarian_bulgaria.md
README-chinese_china_simplified.md
README-dutch_netherlands.md
README-french_france.md
README-german_germany.md
README-japanese_japan.md
README-russian_russia.md
README-spanish_spain.md
README-swedish_sweden.md

Directory Structure

default/
bulgarian_bulgaria/
chinese_china_simplified/
dutch_netherlands/
french_france/
german_germany/
japanese_japan/
russian_russia/
spanish_spain/
swedish_sweden/

Thoughts? I'm trying to match the way we handle GetText so that we can eventually link from within Cacti and present documentation in the language they are using if it is available.

netniV commented 6 years ago

Seems OK. Any thoughts on using the 2x2 codes over the elongated versions? eg, en_US as I’m pretty sure that is what we use in the background in the locale detection/assignment.

netniV commented 6 years ago

I think we should close this issue now that we have a more formalised Document Standards and open the issue of multiple languages as a separately tracked issue.

Cacti / documentation