Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I'm writing a specification document for my website (it's a school project, btw). I currently have some proze about the overall layout and theme of the website, how you navigate through the website, and a brief description of the contents. I however do not have a list of all pages; should I include that?
Also, how can I determine the technical specifications for my website? I know, for example, that I need PHP 5 (or compatible), but I'm not sure what version of HTML, CSS and JavaScript to ask for. How can I determine these requirements?
I would think that the list of each page would be included in the Navigation section of your document. Also to determine which version you HTML, CSS, and Javascript might I suggest using a blanket "Use of standards compliant HTML, CSS, and Javascript which will render in all major browsers". Or something similar. You don't necessarily need to pidgin-hole yourself into using a specific format as long as it does what you want in the browsers you want.I think a good requirements doc would steer away from making decisions like this for the developer and stick to decisions such as what the content looks like, what the navigation map is, what content to provide, and functionality.
As an example of what standards there are for HTML, if you want your page to "validate" as a particular HTML standard then you would want to indicate that version in the header but the header itself is unnecessary for the browser except to tell it to render in standards or quirks mode. For a "standards" mode site use of the HTML 5 doc type is all that you need.
The HTML version can be found in the first DOCTYPE tag, usually on the first line:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
In this case, it's XHTML 1.0 Transitional.
As for CSS, most browsers use version 2, but it's trivial unless you're using some crazy new CSS features slated for the next release. For javascript, according to the wikipedia page, the latest version is 1.8.2. This again doesn't really matter that much, differences between Javascript versions are usually extremely minor.
Writing a technical spec.
Answer the following questions.
1) What is your site for? What purpose does it serve?
2) Who is the site made for, do they buy into the answer to question 1?
3) The audience from question 2... what type of computers / devices will they access the website from?
From answering these questions you will know the minimum requirements that you have to design for. For instance, if everyone you are marketing to is older with ancient hardware (develop in straight HTML no javascript, use tables for layout) ;) If you are aiming for a younger, computer savvy audience, develop using HTML5, CSS3, jQuery.
Server side tech doesn't make a difference unless you are trying to create a site at scale. (to support millions of users)
I would include a sitemap (list of pages)
Related
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 2 years ago.
Improve this question
I am building an admin style, data-driven, internal business application (as opposed to a public facing website). I'd like to use a Bootstrap based template (even considering for-purchase templates from a Bootstrap marketplace or something), but the key requirement is that the site must be accessible (WCAG 2.0 AA compliant).
I know Bootstrap has had some accessibility issues (some colors, some javascript, etc.), but I also know that a lot of that has been getting better as newer versions were getting released. Bootstrap documentation itself offers only a small section on Accessibility and no mention of WCAG 2.0. Does anyone know what the latest status is for accessibility and Bootstrap (ver 3.3.7 at the moment)?
I've also come across Accessible+, which is a Bootstrap-based template, but I'm not sure whether the design fits well for the application I'm building, as it seems more public-facing (product/sales based). But it might work.
Alternatively, does anyone have any other Bootstrap based templates to recommend (free or not) which would work well for my need here, while also being very accessible?
I develop and maintain custom bootstrap websites that emphasize WCAG 2.0 AA compliance, but I'm looking for a good Bootstrap based template from which I can develop smaller projects without investing the time for a custom project.
One thing I'm noticing is that the few templates and themes out there advertising as WCAG 2.0 AA / 508 Compliant are NOT actually compliant, including Accessible+. Using the online WebAIM tool on their template it's registering 8 WCAG 2.0 AA coding errors, 16 alerts, and 4 contrast errors on the front page.
The WebAIM online tool is just a starting point, even getting zero errors on the tool does not make a site "compliant" there is no such thing as a "compliant" website ... the criteria is subjective. There are less and compliant and more compliant sites.
Validating with the WebAIM tool does definitely make a site more compliant. To get any sort of certification that a site is compliant actual lab testing by individuals with disabilities is required. Even then, a site can get a certification from the third party that does the testing, there is no universal compliance stamp that the Dept of Justice would refer to if a complaint was filed for a site.
Another thing I've found is that one needs to be careful about what third party to use for a certification of a site. Some are very expensive and do not necessarily have much credibility. The non-profit WebAIM program at Utah State University is one of the most credible and reasonably priced. Their site also offers some of the best overall information about web accessorily and compliance. Note, I have no affiliation whatsoever with that organization other than attending training there.
I'm in the same situation. I'm not sure about how the accesibility of Bootstrap has been improved since the 3.1.1. version.
I also saw the Accessible+ template, but it has been not updated since January, and I'm not sure if can fit what I need, so paying for it will be my last option.
These were my two main options:
Assets CMS GOV Framework. Its a modification of Bootstrap 3.1.1 with accesibility improvements to acomplish with the section 508 compliance (kind of USA govern alternative to WCGA 2.0, but a little less restrictive than WCGA AA). You can find it here http://assets.cms.gov/resources/framework/3.4.1/Pages/ the problem is that the package is just a bunch of folders with different scripts, styles, etc and I don't know where to start. I took a look to a previous version of the framework http://assets.cms.gov/resources/framework/2.0/Pages/ which was based on Bootstrap 2 and those files seems more like the kind of content I was expecting to find when I download it. So... after a couple of hours thinking if all those folders in the package wehere modificated, or where the originals and how to start, I declined about it... Maybe you can see it more clear.
The other option, which I'm starting to use, is the current Bootstrap version, with the Paypal Bootstrap plugin for accesibility https://github.com/paypal/bootstrap-accessibility-plugin. This seems more clear for me to figure out how to use, but is from 2 years ago and I don't have too much hope about it.
Anyway... both options are from a couple of years ago. I spent two days searching for anything else but seems that nobody cares a lot about accessibility nowadays. Several changes in accesibility have been implemented on Bootstrap since 3.1.1 but I think still can be far from be ready for a WCAG 2.0 AA.
In Bootstrap 4 beta seems to be more accesibillity improvements, but I don't know if they are enough to accomplish the WCAG 2.0 AA standards.
It will be good to know if you find something interesting!!
Disclaimer: I am the author of Accessible+ accessible bootstrap template as linked here by the question opener.
Accessible+ is in fact based on ASSETS which is based on Bootstrap.
I developed it because there were no Bootstrap accessible options available.
The main purpose was a regular template for "non-admin" websites.
Since I did not get overwhelming requests for doing an Admin template version, I never took the time to design one. But - I might in the future.
In any case, I can offer personal customization, even if you ask me to just make you a general "skeleton" for admin side.
Thanks for choosing to buy the template, I know it doesn't suit your needs 100% and I hope you succeed in converting it the way you need.
I was searching as well in the past for an accessible Bootstrap 4 template but found nothing. The ones I found failed in most accessibility tests.
Recently though, I searched again and found the "Labinator A11y-Bootstrap" template. It is basically an accessible Bootstrap 4 premium template that satisfies the WCAG 2.1 Level AAA guidelines. It also comes with an accessibility toolbar.
If you need though a free template and have good coding knowledge, then any modern Bootstrap 4 template can be made accessible with proper expertise in web development and accessibility. You can start by reading the official accessibility page of Bootstrap at (https://getbootstrap.com/docs/4.4/getting-started/accessibility/) then familiarize yourself with the WCAG 2.1 Level AA/AAA guidelines. There are some helpful checklists for those online, especially at the official website of WCAG.
Thereafter, you have to test your template with several web accessibility tools and verify the results manually. Two good tools are AChecker.ca and wave.webaim.org. Please note that all current web accessibility tools are not perfectly accurate - take them with a grain of salt. They can serve as a good pointer in the right direction rather than an ultimate guide.
It is good to note as well that Bootstrap 4+ is much better in terms of accessibility than Bootstrap 3+. As a full-time web developer working in the field, I would never pick Bootstrap 3+ or any template based on it when we have the modern Bootstrap 4.
I hope that helps!
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I am looking into using a wiki (prefer mediawiki, but not a req.) as the repository for developer generated documentation (User Guides, Release Notes, Application Notes, Errata, etc.) from a collaborative/easy-to-update point of view a wiki seems like a good match, however since this documentation will ultimately ship to customers we want to be able to export the documents in their final state (e.g. during the release cycle) to static versions that no longer include histories.
Ideally the export would leave the document in a form (i.e. word doc, or legible HTML) where updates could be easily made by a non-programmer.
It would be good if niceties like section ordering and table of contents were available, or easy to add after the fact.
Are any tools with features like these available?
It sounds like you need a step in your dev cycle that will take your HTML wiki contents and "documentify" them - doc/pdf/html for simpler delivery. If that's right, you could try something like Docmosis or JODConverter which can act as engines to do the conversion. The last step would be working out how to integrate it and have it automatically extract your wiki content to transform into a document.
I'm a little confused.
If you want to ship the documentation in a formal like HTML, how would users continue editing? (use DumpHTML to generate HTML).
If you want to ship the documentation in Wiki form and allow users to continue editing, why not just replicate the database and get rid of the change history until a certain point? AFAIK MediaWiki has some support for this.
One option would be Mylyn WikiText, which is used by some Eclipse projects to generate Eclipse documentation from the Eclipse wiki (which is based on mediawiki). WikiText also supports other wiki markup (trac, textile, etc.) and other output formats (docbook, HTML, etc.).
In MoinMoin Wiki you can export to DocBook. DocBook can be converted to professional looking PDFs.
DokuWiki uses plain text files as storage backend which can be simply copied to your project as documentation.
First, don't discount that MediaWiki has a permanent link function. So, if you allow the readers to access your wiki, you can just send them a URL to a specific version of the page.
Alternatives - you can print a PDF. Wikipedia uses the Collection extension but there are others.
Finally, if you use Firefox and want a client side solution, use PrintPDF
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
Currently the documentation where I work is in a bit of a state. There isn't anywhere near enough of it, and the documentation that does exist is spread out over many word documents making it hard to find anything.
I'm trying to take some initiative and get it improved, and I figure the first thing is to find a better format to write the documentation in:
My thoughts are that the documentation should be structured in a series of short articles (MSDN / Html Help style) and structured in a suitable tree:
It would be good to be able to produce a standalone Html-Help style package to be shipped with the application
As well as being able to produce a MSDN-style website as a reference for those who are too lazy to look at the CD.
Search is of course a must-have
It needs to be at least reasonably easy to update - if there is a 17 step process to update the published documentation then it makes it seem like too much work to do simple changes, and nobody can ever be bothered to update it.
The documentation is technical in nature, and so ideally it would be nice to be able to include generated documentation from things like the Xml documentation embedded in C# code. This is however definitely a side-requirement - currently very little useful Xml documentation exists, its just that in the future I plan to fix that.
For the same reason it is often good to be able to handle things like attachments (code samples etc...) I'm not expecting anything fancy, but this is something I need to bear in mind to make sure that its at least not handled badly.
Are there any projects or languages that are suited to this sort of documentation?
I've had good results with doxygen on my C and C++ projects although it supports many other languages as well. You put the documentation in comments in the code that can be simple or complex HTML markup. It is very easy to update as it is part of the code. You can make building the documents part of your build process. Additional topic that are not strictly API related can be added as separate HTML documents. The version I'm using doesn't support search so you would have to add another product to search these pages. Because it is HTML you can add in code samples, diagrams, etc.
If you use LaTeX you can get all your documentation in great looking PDFs and printed copies, as well as being able to generate html (via latex2html). TeX has the advantage of being all plaintext, too, so you can track/merge it reliably with your favourite revision control system.
We use confluence as our documentation repository. It is fairly easy to have public and private sections, and has a nice WYSIWYG editor. It can handle attachments and can be saved off as PDF documents if you like.
I've used robohelp with good results. it is plain html, but has a generation process that keeps everthing looking consistent. It can be packaged as a .hlp file with the app, or published to the website. Check it out, it is simple so you can get back to doing your job :)
A clean way is to use DocBook. It is easy write and undetstand. It is also easy to parse as XML parsers are standard and other forms of documentation (e.g. from the embedded documentation in comments) can be easily be transformed to this format.
It is straightforward to generate PDF, HTML og other formats from the DocBook source (tools exist for this purpose).
I've started using DokuWiki. Its not exactly what I was originally looking for (I think I was really looking for a CMS), but it does the job and some respects its better than what I originally had in mind (in particular its a wiki - I've not yet gotten as far as publishing this to our customers however so I'm not sure how well thats going to work out)
I'm using the IndexMenu plugin and the Arctic template to get a navigation tree on the left, and if I publish the wiki itself I'll use the discussion plugin to allow users to post feedback.
Currently my method of handling generated content is to use xslt templates to produce dokuwiki syntax, and write that output directrly to files / folders in the "data/pages" folder.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 9 years ago.
Improve this question
We would like to prepare the software usage documentation for a web application. This mainly contains the screen shots ( along with relevant documentation ) in most of the pages. Also we would like to have a top menu links using which we can jump to the corresponding pages.
Please suggest the tools which can be useful to fulfil the above requirements.
Dr Explain is pretty nice.
http://www.drexplain.com/
It will analyze your page and create a list of controls, buttons, etc. that need callouts.
If you write your documentation with a particular documentation tool in mind, outputting to HTML is relatively simple. LaTex, markdown (with Pandoc in mind), reStructuredText (with Pandoc or Sphinx in mind), AsciiDoc (with DocBook tools in mind) and DocBook (with Docbook tools in mind--see Pandoc).
All of those formats would allow you to easily organize your documentation then export them into HTML however you deem appropriate (probably by major heading, then build a simplistic wrapper around the files). Sphinx can also just output web-based documentation (see Python.org's documentation).
For screenshots I suggest using a standalone app on your platform of choice, Ideally one that lets you do annotation within the program. Skitch for Mac, Jing for Windows, Shutter shutter-project.org or Jing in linux.
Finally I would suggest also doing screencasts as they can be especially helpful to show off the interestingness/power of a web-app.
This may be overkill for your project, but I've favored preparing documentation in docbook (xml), since it's fantastically portable/convertable.
To simplify the document creation, you could turn to http://www.oxygenxml.com/, but you can also do the same work in just about any other xml (or even text) editor.
Once your document is prepared, it's trivial to generate html (multi-page, or single page), and pdf versions.
I don't know what king of language you are writing your code, but in the case of Java, you can use Maven.
With maven you can use many plugins, like JavaDoc, site that create a site with many informations about your API/software and contains the top menu that you want.
This is a screenshot of the site that maven generates: link
I hope these could help!
Cheers
I'm sure there's some awesome tool out there that integrates everything needed for usage documentation but I'll tell you what I use!
I use wink to grab screenshots of the application in use. I tend to fire it up and just grab loads of screenshots as I walk through the application, or even just a part of the application. Next, I edit the project in wink to remove redundant screen captures, re-order them and position the mouse on each frame. I then add highlighting which is usually just a nice box around the part of the screen I am demonstrating. Wink allows you to overlay the images with informational boxes and arrows, I then export the project as html and use the numbered, exported png images as the base for my documentation.
I tend to drag them into OpenOffice Writer (or whatever you are using for typesetting) and supplement them with more information - ie a few paragraphs top explain what the user is doing and why.
We use acrobat to output this documentation and providing your table of contents is done properly, it can insert bookmarks in the pdf to enable jumping to relevant sections.
The main benefit we get from wink is that it is very easy to re-grab shots when things change and it can output to flash to provide nice, snazzy demos of small pieces of functionality for posting on the web.
Closed. This question is off-topic. It is not currently accepting answers.
Want to improve this question? Update the question so it's on-topic for Stack Overflow.
Closed 9 years ago.
Improve this question
When you print from Google Docs (using the "print" link, not File/Print) you end up printing a nicely formated PDF file instead of relying on the print engine of the browser. Same is true for some of the reports in Google Analytics . . . the printed reports as PDF's are beautiful. How do they do that? I can't imagine they use something like Adobe Acrobat to facilitate it but maybe they do. I've seen some expensive HTML to PDF converters online from time to time but have never tired it. Any thoughts?
If you are specifically looking at how Google does it. If you look at the PDF Properties page, they use Prince 6.0 (see princexml.com)
There are lots of other PDF generators out there. I've had great success with PDFlib for tricky jobs.
iTextSharp and iText are opensource and free PDF generation libraries for .NET and Java respectively.
I've used them to generate report PDF's before and was quite happy with the results.
http://itextsharp.sourceforge.net/
http://www.lowagie.com/iText/
Great free alternative to PrinceXML: wkhtmltopdf . There are plenty of wrapper libraries for various languages - but I've only used Ruby ones. However the product itseld is on par with PrinceXML IMHO.
I have had success with pd4ml. It has a tag library, so you can turn any existing HTML into PDF by
<pd4ml:transform>
<!-- Your HTML is here -->
<c:import url="/page.html" />
</pd4ml:transform>
Well, I doubt it's as easy as generating HTML . . . I mean, first of all, PDF is not a human readable format and it's not plain text (like SVG). In fact, I would compare a SVG file to a PDF file in that with both you have precise control over the layout on a printed page. But SVG is different in that it's XML (and also in that it's not supported completely in the browser . . . still looking into SVG too). Come to think of it, SVG should probably will be my next question.
I know Google doesn't use .NET and I doubt they use Java so there must be some other libraries they use for generating the PDF files. More importantly, how do they create the PDF's without having to rewrite everything as a PDF instead of as HTML? I mean, there has to be some shared code for between when they generate the HTML view as opposed to the PDF view. Come to think of it, maybe the PDF view and the HTML view are completely separate and they just have two views and hence why the MVC development style seems to be the way to go.
Rendering a PDF is hard, complex problem. However generating them, is not. Simply make up some entities, and generate. It's about same problem domain as generating HTML for webpage vs. displaying (rendering) it.