So I have release my first attempt at making a PDS contribution (teacher charts). I thought I would throw this out for discussion. Documentation/Implementation instructions. My documentation sucked. I know this. I just wasn't sure on what information was need and what information made it seem patronizing. I noticed the many Customizations come with pre-made page to link to it (ie. the teacher's home page). I am just wondering to myself, is this the best way to Implementation instructions? Would it be better to give instructions on how to create the link and maybe a small example or is the pre-made page better. I find the when I use customization from PDS, I rip only the important pieces out. I will rearrange the files in a new folder structure to match my own and add links and images where I see fit. When I use a customization, the only information I need is what page to link to and what parameters are needed to be sent. Maybe creating a set of guidelines or structure (like PowerSchool Release notes) would be useful or is this just recreating something the is already there and I don't know how to use it?
Just some ramblings of a mad man.
Comments
My $0.02
Since I haven't ever contributed anything before, you can probably consider this a user's perspective rather than that of a fellow developer.
I've implemented a LOT of customizations from others (not just PDS, but ALS and some neighbor districts). Including a page with the link is VERY helpful, because - even if I don't use it - having it there shows me how to implement it, and make it mesh with my system. I've seen documentation that includes a code fragment that will call the report, and the URL of where it should go, and that works great too.
Point is, a fully functional modified home.html-type page will help neophytes get your customization working, while more experienced users will know how to pull the data they need out of your home file and put it into their own.
Therefore, I vote for uploading a modified home file. Maybe include some sort of a caveat that if you copy the whole folder over, you may nuke your already-customized home file, or maybe rename your file (homeTeacherCharts.html) for instance, so it's there and all the newb has to do is rename it, but you've protected the not-as-newb from hosing his own customized file.
re: Learning from my mistakes
I don't know if you've noticed but there are a lot of questions on where to put the links and why things don't work. Without putting a page up that has the link included it makes it very difficult to troubleshoot and get it working for everyone.
Something to think about.
Jason Treadwell
Custom Solutions Specialist
jason@powerdatasolutions.org
www.powerdatasolutions.org
RE: Learning from my mistakes
For linking I have been adding a file with the link built in already and also documenting the link code required for anyone that wants to insert their own link to the customization. As I get around to having more customizations that get linked from the same source, I think I may just include documentation about creating links to the main customization pages and no longer include the modified home.html or other pages that just have links.
Screenshots seem to make a big difference. I use an add-on in Firefox called FireShot to make the screenshots. Its quick and easy to capture the page you are looking at and edit the image. I like using that add-on since I can blank out any student info and add annotations and have a finished screenshot in a couple minutes.
Brent Johnson
Database Specialist, Programmer
Traverse Bay Area ISD
RE: Learning from my mistakes
Does the FireShot allow for the editing, or do you need an image editor?
I currently use the PrintKey2000. It's a discontinued freeware that captures the Print Screen Key. You can capture full screen, objects, rectangles, etc. The only issue is that you need a image editor to make any changes. Since it's a separate application, you can do screen shots of anything that's visible on your screen.
Dan Berman
RE: Learning from my mistakes
FireShot has its own built-in editor, but you can also save the image immediatly and use your own image editing tools. One disadvantage with the free version is that the editor prevents you from browsing. They offer a licensed version that removes that annoyance and adds other features, but I get by just fine with the free version. You should be able to take a look at it here: https://addons.mozilla.org/en-US/firefox/addon/5648
I've used PrintKey at a previous job and it was nice to use for screenshots of other applications, but I've found that FireShot is very simple when doing web documentation.
Brent Johnson
Database Specialist, Programmer
Traverse Bay Area ISD
RE: Learning from my mistakes
Nice find on the addon.
Does anyone by any chance have a recommendation for a similar program for the Mac? The editing feature would be huge for us, but with most of my co-workers being mac only...
Thanks.
Dan
RE: Learning from my mistakes
Brent,
Thanks for sharing this addon - I added it to Firefox and it works slick. I use IE as well and when it asked if I wanted to use it with it also I went ahead and let it add itself to IE and it looks like it works okay with it as well.
Matt
RE: Learning from my mistakes
In my opinion, people should just create the links where they want them. There's just so many pages out there now and if I included a page with a link for each one of my customizations I'd be overwriting my own pages and everyone else's with links :) On the teacher side, I started linking from the backpack area because linking from the home page was becoming too cumbersome. Or where I think a link should be may not be where someone else wants it. For example, with a PowerLunch page, someone may want to put it on the reports page but someone else may want to put it on the PowerLunch Manager Screen. Unfortunately a lot of people aren't familiar with creating links. I've had a lot of people ask me how to do it so I just went ahead and put up an article one day in the Basic Article area of C101 to help people with it. Also, I think once people realize there's no real magic in most cases when it comes to where links appear - most pages in PS are just links pages to other pages - then deciding where links go is less confusing.
The other thing I think is important, and I'm a big believer in, is screen shots. I think it's good to let people see what they're getting visually. If you're an ASP customer and don't have a test server, you have to send in the customization and if you don't like it then you have to ask them to remove it, etc. Or even if you're not an ASP customer but don't have a test server, the screen shots will give you an idea of what it should look like when it runs. Unfortunately screen shots take time to do and with a site like this it may be hard to embed them into pages. I like though how Brent is including some with his customizations by uploading the jpgs.
Matt
re: Learning from my mistakes
How to properly document has always been a large problem. What I have found really needs to be included with each customization is:
After that items are added depending on what the customization is and how clear is it what you'll need to do. Most of the time when I do reports I like to include a copy of what the link would look like if you stick with the structure I packaged it in. However I also include a copy of an existing page with the link OR tell the user where to find another download that includes that link. But in reality I'm reacting to what people ask of me.
Documenting within pages gets touchy. Any comments you add to a customization count towards the 32K limit. I've had to remove comments before to make room for the page to make it work due to page size limitations. Dean recently released a customization that included a help file. That could be a way of documenting.
But we need to remember that many people just want to download and install. It is possible to over-explain and many (perhaps most) people who become good at customizing learn from exploring, not from being told.
What I know I could be better at is including screen shots and perhaps video of what the pages do. I think that would help out a lot and would help at the most basic level which is probably the best place to start. Another thing we might consider doing is writing user manuals for each customization. My department makes them for anything I make or install that is used by teachers. Having these would probably be beneficial for all involved.
I'm interested in hearing anything else people think is needed. But it'd be good to know what is needed and what is wanted. So many times I hear "I need" when they mean "I want". It's good to consider that the more documentation that is needed the slower it will be to create things, post things, and make changes. When making changes means redoing all the documentation then I know I'll be much less likely to post every upgrade I do. As it stands now I have tons of stuff I never released because I just haven't written it up yet. Documentation takes time, and we are doing this for free.
Jason Treadwell
Custom Solutions Specialist
jason@powerdatasolutions.org
www.powerdatasolutions.org
re: Learning from my mistakes
I'm working on finishing my second PDS contribution and am thinking the same things. With the number of pages that are having things linked from, I think it's difficult to just include a page like the teacher home page. Some people could have different combinations of the customizations or have different orders for the links, etc. To say copy this file over doesn't help the user integrate the customizations.
For my documentation, I'm trying to do a combination of both. For instance with the teacher home page, in the documentation is the code needed for the links on said page. I'm also listing other files that this code could go in, and including a renamed home.html page(home-example.html) so that a user can see what it should look like.
Another aspect to consider with the documentation is when dealing with the admin pages, you may need to worry about not only the instructions for the links, but how to adjust the breadcrumbs as well. There could be enough little changes to document that it may be easier to include those linking files.
Another aspect for documentation, I added a comment at the top of most of the pages listing the customization name, my name, and the version it was last updated. I saw a comment about versioning the PDS and it seemed like a good idea. I think it would help reassure users which files have been updated in case they are used in multiple customizations.
If you find a structure, pass it along, I know for the instructions I'm following some of the examples that others have been using, where it's listing the files that have been modified from original, what's new files, how to install. I may add a little like how to use, etc.
But then I'm in the minority for customizations so don't take this as gospel.