User talk:Zha Ewry/Proposed AWG Process

• I think that this accurately describes the process path that AWG seems be travelling at this point. Of special note is that it identifies that the work is being addressed from multiple viewpoints in parallel, and that trial implementations of parts of the system are being made early as this is of special interest to several participants. It looks good to me, a recipe for teamwork.

• The final "code it and test it" is of course just a placeholder, but still funny in its terseness. :-) No doubt we'll expand it more usefully before long, especially in terms of Quality Assurance, elements of which will end up within earlier stages of your process. For example, traceability from viewpoint concerns to elements in the design is an important aspect of QA work, one which the VAGs will be addressing. Likewise, incremental change and regression testing is paramount in a distributed grid where the sun never sets, so we'll have to think about this in the "code it and test it" section in due course. --Morgaine Dinova 02:01, 18 October 2007 (PDT)

• What? I'm not supposed to have a sense of humor? :-) And... on a slightly less humorous note, it never hurts to keep that final goal in mind. The rest of our points are well taken, and I've tweaked the page to reflect them. - Zha 5:33 AM PDT, 18 October 2007

• Until there are resources for the AWG Project in a JIRA domain (hosted by LL or elsewhere), I propose we use several "office hour" style allocations to gather about each subject area or discuss in a geographic-region friendly manner. That way the "groups" as suggested by the VAG proposal can actually show membership by being present at the office hour. That office hour only needs agendas to work on any viewpoint (placed on the agenda) instead of being limit to just the one listed on the current form of VAGs. What we need for these office hours are viewpoints, subjects, participation, the agenda, and the hour the dicussion takes place. Maybe two or three of these are enough for now that'll be friendly to Europe, America, and one other common timezone. Dzonatas Sol 11:36, 18 October 2007 (PDT)

proposed process ideas from Dzonatas Sol =

Dzonatas Sol

How To Use This Template

• Review Design Document Template for insight of needed content.

• Design Documents are to describe aspects of the given model. Terminology that is out of scope to describe a specific aspect of the given model belongs in the Glossary and does not need its own design document. Rationale: the design documents under this category are specific to the given model. If the title of a design document has the same name of a term that confuses the view, it is best to find a new name for the title of the design document; however, the previous model and the given model both already provide names for aspects of that model, which are commonly used by default for design titles and may confuse the view more if changed. Icons also help to avoid confusion such the icon plus a title can be recognized distinctly from general terminology.

• Title each page with "AWG NAMEOFDOC" where NAMEOFDOC is the actual name. If possible, upper case only the first letter of each word in NAMEOFDOC, as it is typically done for a title, like "AWG Document Title." The first four characters "AWG " are significant to the macros.

• Start each page with {{:AWG/PageHeader}} in order to transclude the header layout (as shown above) and its macros.

• Avoid generalizations in the Description field. As much as possible, write statements in terms of the now, which means there is an actual model to describe. Also, the use of grammatic infinitives is a bold indication of a generalization (some usage in nouns is unavoidable). Remember, any generalization in design is a bottleneck in implementation.

• Keep the Description field concise but mappable. Use {{AWG|NAMEOFDOC}} to map to other AWG design documents. Any specifics beyond basic purpose, terminology, or mappable usage goes in another section (and refer to Design Document Template for possible sections). The description being mappable to other design documents is a power of the wiki -- use it! (especially to map back to the article itself, for example "A {{AWG|NAMEOFDOC}} is ...")

• Upload an icon for the page under the name AWG_NAMEOFDOC.png where NAMEOFDOC must have underlines instead of spaces. A macro in the pageheader detects the image and inserts it automatically. For now, the icons are sized to 100x100px. Icons are a good means to graphically map the model or indicate states of the model, so it is good to keep them distinct from each other (or redo them to make them more distinct). Don't make icons too complex where it cannot be easily drawn by hand as a conversation piece.

• Use regular wiki sections below the pageheader. For example if there are specifications to list, create a "Specification" section for them.

• Any talk in the main article is subject to be rewritten to make a formal statement about the design or can be moved to a more appropriate (discussion) page.

Goals

• The goal of these AWG Design Documents are to use the abilities of the wiki to create a concise description of interest, with such wikification, in order to express, discuss, and verify a given model being designed. Each article is given workspace for views and viewpoints. The description of interest, being wikified, is navigatible, by its wikicode, to other related design elements. The specifics of each link is tied a each design document in order to augment to consistency of the descriptions with other design documents. Thus, it is possible to verify the given model, and potential any new model, before any implementation because the links avoid generalizations and gives precise directions. Nevertheless, this does not automate the process nor mandates how to write the descriptions, it is provided only to be helpful to both those that design and those that implement the model.

• A secondary goal is to help prevent discussion sprawl. Wikis allow the freedom for discussion to take place on multiple pages, and the intention of the navigational links is to help direct the flow of conversation to the given model. This has already proven to work, but the approach needs refinement to encourage the pull of interest to be less disjoint.

• Also, these design documents provide constructive methods that are useful to visual people, which is positive in accessibility issues.

Design

• The guidelines above explain the technique used to make the best of this template. The use of transcluded Description page allows the wikified text (of the description) to be transcluded in other areas of the wiki, which then serves as an informational and navigational instrument.

• NOTE: If you are familiar with the old MOOs, Zorks, and Adventure style of games, then you will have a perfect example of how the Description should work but with a much more point-n-clickly style of interface instead of keyboarded input to explore! This is comparable to modern S.E.E. tools. (No doubt such environments are based on older Adventure games!)

• AWG_Design_Document_Template, for example, is the main design article and workspace that can be edited more freely, which is where the main discussion should take place.

• AWG_Design_Document_Template/Description, also example, is the transcluded "navigational" Description field, which needs finer structure to ensure a navigational Description functions well with wikilinks to directly related design documents.

• The ability to quickly move into a (standard) functional design process and detailed design phase from a general framework or given model is not stated as an explicit goal; do notice the enabled ability to move from a raw conceptual model directly into same standard detailed design process. S.E.E. tools (and MOOs, etc) probably provide a much easier way, likewise, to automatically link/unlink descriptions with each other unlike a wiki, but the wiki provides access to history of changes.

Interface Requirements

• Besides the normal use of a wiki and the guidelines above being followed, the user only has to include the wikicode code transclude the description if that is the only text desired from the design document and its workspace. One example of wikicode to include the above description in the header: {{:AWG/AWG_Design_Document_Template}}

Performance Requirements

• Specifics of load on the wiki are not known. In general, transcluded pages are updated in the cache as one page, but it still requires extra access to generate the complete page than a single page with no such inclusions. However, the pull of interest is a factor to consider on the span of documents being edited without any helpful navigation. If these templates are found useful, as useful as the wiki itself is as a template, then the growth of articles is expected to be the same, but that is with the assumption a core of documents with these templates are already done to describe the model.

Security Impact

• The description of interest becomes more accessible, and its nature to be transcluded allows for one change to make a wider impact. If abused, a request for augmented security might be needed. However, Wikipedia has shown high tolerance before such preventive measures are of need. If a model becomes final and implemented, it may be reasonable to lock the description pages of the that model and start with fresh new design documents for the next model.

Community Concerns

• As the design progresses, parts of the model not yet described may appear broken.

Support

• Support is limited to the communication channels available. I've found it costly, so far, but I also have learned how to continue to make progress in the design, which is priceless.

Limitations

• The in-line DISPLAYTITLE function of the wiki either is not available or not well documented. There is a special:displaytitle page, but there also exists hints of a wiki magic-word that can be inserted in each page in order to make the title display differently from its URL scheme. I have a hint that such feature may not be fully implemented as of yet due to RESTful desires to keep the title and URL scheme very similar. For now, the URL scheme and display title are similar by such limitation.

Interactions

• The use of wikicode with HTML works, but wiki users still are in disagreement if HTML is a feature of a wiki. There is HTML in the template in order to use the CSS styles. The transcluded page and the macros of the template have already replaced much HTML code that have been used in the past in like style.

Testing

• The approach of these design documents have been a way to test the test. Besides the progressive design and the appearance of being broken when not fully described, it basically passes that test. =) The subsequent test then becomes a need to continue the design and verify the model. The current progress has already found a flaw in the given model in the same way this may appear broken.

Deployment

• Besides a fresh start, continue design of the model here with these design documents!