Differences

This shows you the differences between two versions of the page.

--- wiki:editing [11 May 2011 23:14] – Approved andyr
+++ wiki:editing [25 Apr 2014 19:29] (current) – re-word with new process Robin Getz
@@ Line 1: / Line 1: @@
-====== Page editing ======
+====== Page Editing ======
-To edit a page in the wiki, simply log in, and click the button labeled "Edit this page" shown on the top of the page. This will switch to editing mode for this page, and you can change the wiki source of this page in an embedded editor.
+Developing Documentation is a combination of editing existing pages that others have created, and/or creating new pages.
-Wiki pages are written in a simple, plain-text [[syntax]], that allows structuring the page and pleasant formatting while retaining high readability of the page source. When you edit a page and save your changes, the previous content will not be lost. Instead it will be saved as an old revision of the page in the [[doku>attic]] and can still be viewed or even restored.
+Wiki pages are written in a simple, plain-text [[syntax]] with a few [[more_syntax|extensions]], that allows structuring the page and pleasant formatting while retaining high readability of the page source. When you edit a page and save your changes, the previous content will **not** be lost. Instead it will be saved as an old revision of the page in the [[doku>attic]] and can still be viewed or even restored.
-Before you edit your first "real" page in the wiki, you should try out the possibilities in the [[playground:playground]]. The playground is provided so that users can test things and play around to their heart's content.  (A playground is created when installing DokuWiki, in the "playground" namespace.
+Before you edit your first "real" page in the wiki, you should try out the possibilities in the [[playground:playground]]. The playground is provided so that users can test things and play around to their heart's content. The playground is wiped out on a daily basis, so feel free to try out things there, and don't worry about making any permanent damage.
-===== Developing Documentation =====
+===== Editing Existing Pages =====
-Developing Documentation will be a combination of editing existing pages that others have created, and creating new pages.
+To edit a page in the wiki, simply log in (you must be logged in, with a valid myAnalog account to edit wiki pages), and either :
+  * edit the **entire page** at once, by clicking the button labeled "Edit this page" shown on the top of the page.
+  * edit **a section**, by clicking the button labeled "Edit" underneath each section. By mousing over this edit button will highlight the section to be editted. Editing sections is sometimes easier, since it is just less text to deal with.
+Clicking on either button will switch to [[syntax|editing]] mode for this page, and you can change the wiki source of this page in an embedded editor. Before saving changes (by clicking on the //Save// button), examine your changes, by looking at a //Preview// or see a difference, by clicking on the //Changes// button.
-==== Editing existing pages ====
+===== Creating new pages =====
-Editing an existing page, is as simple as going to that page, and clicking on the //Edit this page// button at the top of the page, or the //Edit// links at each section break. Editing sections is sometimes easier, since it is just less text to deal with.
-Before saving changes (by clicking on the //Save// button), examine your changes, by looking at a //Preview// or see a difference, by clicking on the //Changes// button.
+There are two ways to create new pages. Both require that you are logged into the wiki and have special access (ie, normally that means you are an Analog Devices employee).
-==== Creating new pages (Requires Special Access)====
-There are two ways to create new pages. Both require that you are logged into the wiki and have special access.
   - go to the page that you want to create (by typing in the exact path), and clicking on the "Create this page" link at the top of the page
   - create a link by editing an existing page, to something that doesn't exist, and then clicking on that link, and then clicking on the "Create this page" link at the top of the page.
-===== Process/Publishing =====
+====== The Creation/Editing Process ======
 Just like paper documentation, the wiki is able to differentiate between revisions of a document that are //Under Development// (which is private, typically for a unreleased product), //Draft//, and those that are //Approved//.
 Public pages will always have a banner at the top of each page, with information about the Approval/Draft status. The banner is color-coded with an icon: A Green check mark for the latest approved version, and an orange exclamation point for all others.
-==== Under Development ====
+The development process is something like:
-Anyone creating a page can add a %%~~UNDERCONSTRUCTION~~%% tag anywhere into their page - and no one can look at it, or edit it except the original author. This allows documentation to be created over days/weeks before it becomes "public".
+<graphviz dot>
+digraph {
+subgraph cluster_0 {
+		style=filled;
+		color=lightgrey;
+		node [style=filled,color=white];
+		"Create new page" -> "Under Development" -> Edit -> "Under Development";
+		label = "Under Development";
+	}
-==== Approvals ====
+	subgraph cluster_1 {
+		node [style=filled];
+		"Edit " -> Draft -> "Edit ";
+		label = "Draft";
+		color=blue
+	}
-Any Analog Devices Employee can //Approve// a page. You do so by editing the page, and ticking the ''Approve'' box, and saving the page.
+"Under Development" -> Approve -> Published -> "Edit ";
+ "Draft" -> Approve;
+}
+</graphviz>
-==== Drafts ====
+===== Under Development =====
-Anyone logged into the wiki, can edit a page, and their version will be saved as a draft.
+When a page is initially created on the Wiki, it will only be visible to Analog Devices employees until it is approved.  A message at the top of the page with the "draft" notice will note that the content can only be seen internally. A page can sit in this state forever, and be edited as many times as the creation team would like.
+Once a page has been approved (by an ADI employee), it will be public and visible to both internal and external audiences.  This allows documentation to be created over days/weeks before it becomes "public".
+Once content is public, any edits made to it will also be public.
+===== Drafts =====
+Anyone logged into the wiki, can edit a page, and their version will be saved as a draft. You do not need to be an Analog Devices employee to edit a page. If you see a problem - please fix it.
 Anyone not logged into the site will see the latest approved revision by default (unless there isn't one). All users can still view any revision of a page if they specifically request it -- whether or not it is approved.
-===== Troubleshooting =====
+===== Approvals =====
+Any Analog Devices Employee can //Approve// a page. You do so by clicking the "Approve document" link on the page header. Multiple people can approve the same page.
+====== Troubleshooting ======
 In some cases, the editing of a page is impossible. This can be mainly for these reasons :

Analog Devices Wiki

Differences

Page Tools